CollectionView

Section: ET++ class description (n)
Updated: automatically Mon Apr 8 20:18:15 1991
Index Return to Main Contents

NAME

CollectionView - displays a list of selectable items in tabular format

DESCRIPTION

The class CollectionView displays a list of VObjects in a tabular format similar to that of the class Cluster and allows the selection of items. CollectionView implements the general behavior for all kinds of lists of selectable items such as popup and pulldown menus, menubars and tool palettes.

Item Collection

The list of items is stored in the instvar coll. This collection is specified in the constructor and can additionally be set with the method SetCollection. It is checked whether all items in the collection are instances of the class VObject. If objects are added to the collection later, then the client itself has to ensure that they are "kind of" VObject.
The CollectionView registers itself as an observer of the instvar coll which enables it to recalculate the layout whenever the collection changes.
Any type of Collection may be used. But if it is heavily modified and execution speed is important, then it is recommended to use an instance of the class OrdCollection because CollectionView very often accesses items in the collection by index.
The destructor of CollectionView always destroys the collection and the contained items. If the items are to be reused, then either single items or the whole collection should be saved before deleting the CollectionView.

Layout

The items of a CollectionView are arranged in columns and rows and the available space for an item is referred to as cell. The layout is determined by the flags eCVExpandCols and eCVExpandRows (see enum CollViewOptions) as well as the instvar cols and the instvar rows which all can be specified in the constructor. Three main types of layouts are possible:

1. number of columns is fixed; CollectionView grows vertically
        - either set the flag eCVExpandRows
        - or set the instvar rows to 0

2. number of rows is fixed; CollectionView grows horizontally
        - either set the flag eCVExpandCols
        - or set the instvar cols to 0

3. square layout; CollectionView grows both horizontally and vertically
        - either set the flags eCVExpandCols and eCVExpandRows
        - or set both the instvar cols and the instvar rows to 0

The items in the instvar coll are aligned column first. For example, in a two column layout the items would be arranged like this:

        1       4
        2       5
        3       6

The layout can further be customized by modifying the instvar gap and the instvar minExtent. The gap is the space to reserve between two cells. The minimum extent contains the minimum size of a single cell. These values can be set with the method SetGap, respectively the method SetMinExtent.
Generally, if part of the layout specification is changed the method Modified must be called in order to recalculate the layout and make the change effective.
To ease the access to the items CollectionView provides several methods to map columns and rows or geometrical coordinates to items or item rectangles and vice versa.

Selecting Items

Single items can be selected with the left mouse button. While the mouse button is pressed and moved the method DoOnItem is continuously called. It forwards the message to the currently selected item, by default. When the mouse button is released the method DoSelect is called. The default implementation informs the next event handlers via the method Control about which item has been selected and whether a single or double click has been used.
The instvar selection stores the column and row numbers of the selected items. Clients may actively modify the current selection through the method SetSelection or the method SetNoSelection.

classes are rarely derived from CollectionView.
class CollectionView is often reused directly.
class CollectionView contains 36 methods.

owner of class:: nobody.
baseclasses:: View
subclasses:: Menu, MenuBar
flags:: CollViewOptions

INSTANCE VARIABLES

coll (protected Collection *)

contains the items displayed by the CollectionView. The objects in coll must be instances of the class VObject. coll is specified in the constructor and can be set through the method SetCollection as well. coll is returned by the method GetCollection. The destructor always destroys coll and all contained items whereas the method SetCollection allows to control whether to free the old collection.
The CollectionView registers itself as an observer of coll and automatically reformats its layout whenever coll is modified. See method DoObserve and method PrintOnWhenObserved.

cols (protected short)

contains the number of columns of the layout. cols is specified in the constructor. If the initial value is <= 0 or the flag eCVExpandCols (see enum CollViewOptions) is set, then cols is computed by the method Update, otherwise the number of columns is fixed.
See also instvar rows.

defaultItem (protected VObject *)

is the item returned by the method GetItem if there is no object at the specified cell. By default, it is an instance of the class VObject (!), but it can be set with the method SetDefaultItem.
The defaultItem is only important when the CollectionView has empty cells. If the layout consists of more than one column and more than one row, then the number of items in the instvar coll may be less than the number of available cells. In this case GetItem returns the defaultItem for the empty cells. If an item in such a layout is selected the client has to check whether it is the defaultItem.
Notice:

gap (protected Point)

is the thickness of the border around single items. In other words, the space between two items is twice the gap. The default value is zero but it can be modified with the method SetGap.

menu (protected Menu *)

is the popup menu of the CollectionView. By default, the menu is NULL and the method GetMenu returns the menu of the next handler. A specific menu can be set with the method SetMenu.

minExtent (protected Point)

contains the minimum size of a single cell. The default value is zero but it can be set with the method SetMinExtent. The actual extent of cells within a row or column is calculated by the method Update and depends on the minimum sizes of the VObjects in that row or column.

rows (protected short)

contains the number of rows of the layout. rows is specified in the constructor. If the initial value is <= 0 or the flag eCVExpandRows (see enum CollViewOptions) is set, then rows is computed by the method Update, otherwise the number of rows is fixed.
See also instvar cols.

selection (protected Rectangle)

contains the currently selected cells. selection is accessible through the method GetSelection. The respective components of the Rectangle do not contain geometrical information but are interpreted this way:

        origin.x    column number of first selected cell
        origin.y    row number of first selected cell
        extent.x    number of columns selected to the right
        extent.y    number of rows selected to the bottom

Whether there is a selection at all can be checked with GetSelection().IsEmpty(). Selected items can be accessed by passing the column and row number to the method GetItem.
If the left mouse button is pressed (see method DoLeftButtonDownCommand), then always only one cell can be selected. With the method SetSelection a client can select several cells concurrently. The method SetNoSelection clears the current selection.
See also method DoSelect.

xPos (protected short *)

is an array containing the horizontal position of each column. These values are calculated by the method Update and are used together with the instvar yPos for layout management, drawing the grid and finding items.

yPos (protected short *)

is an array containing the vertical position of each row. See instvar xPos.

INSTANCE METHOD LIST

client interface: CollectionView
GetCollection
SetCollection
SetDefaultItem
drawing: Draw
DrawGrid
implementation: ~CollectionView
layout: GetMinSize
SetGap
SetMinExtent
SetOrigin
Update
mapping: GetItem
InvalidateItemRect
ItemPos
ItemRect
PointToItem
menus: DoCreateMenu
GetMenu
SetMenu
miscellaneous: Parts
PrintOn
PrintOnWhenObserved
ReadFrom
scrolling: ConstrainScroll
DoKeyCommand
selection: DoLeftButtonDownCommand
DoOnItem
DoSelect
DoSelect2
GetSelection
SetNoSelection
SetSelection
updating: DoObserve
Modified

FILES

declaration:: CollView.h

KNOWN PROBLEMS

The method DoLeftButtonDownCommand creates instances of the class CellSelector that does not allow to select more than one cell concurrently though the implementation of CollectionView would allow this.
Other problems: see method DoSelect, method Draw and method ReadFrom.

HISTORY

joe@csesbg.at  Fri Jun 28 14:49 1991   instvars

joe@csesbg.at  Mon Jul 01 17:11 1991   methods

joe@csesbg.at  Mon Jul 01 21:10 1991   main description

gil@csesbg.at  Tue Jul 09 14:54 1991   reviewed

chris@csesbg.at        Thu Jul 11 20:32 1991   reviewed

man2html: unable to open or read file ../mann/CollectionView::CollectionView.n

man2html: unable to open or read file ../mann/CollectionView::ConstrainScroll.n

man2html: unable to open or read file ../mann/CollectionView::DoCreateMenu.n

man2html: unable to open or read file ../mann/CollectionView::DoKeyCommand.n

man2html: unable to open or read file ../mann/CollectionView::DoLeftButtonDownCommand.n

man2html: unable to open or read file ../mann/CollectionView::DoObserve.n

man2html: unable to open or read file ../mann/CollectionView::DoOnItem.n

man2html: unable to open or read file ../mann/CollectionView::DoSelect.n

man2html: unable to open or read file ../mann/CollectionView::DoSelect2.n

man2html: unable to open or read file ../mann/CollectionView::Draw.n

man2html: unable to open or read file ../mann/CollectionView::DrawGrid.n

man2html: unable to open or read file ../mann/CollectionView::GetCollection.n

man2html: unable to open or read file ../mann/CollectionView::GetItem.n

man2html: unable to open or read file ../mann/CollectionView::GetMenu.n

man2html: unable to open or read file ../mann/CollectionView::GetMinSize.n

man2html: unable to open or read file ../mann/CollectionView::GetSelection.n

man2html: unable to open or read file ../mann/CollectionView::InvalidateItemRect.n

man2html: unable to open or read file ../mann/CollectionView::ItemPos.n

man2html: unable to open or read file ../mann/CollectionView::ItemRect.n

man2html: unable to open or read file ../mann/CollectionView::Modified.n

man2html: unable to open or read file ../mann/CollectionView::Parts.n

man2html: unable to open or read file ../mann/CollectionView::PointToItem.n

man2html: unable to open or read file ../mann/CollectionView::PrintOn.n

man2html: unable to open or read file ../mann/CollectionView::PrintOnWhenObserved.n

man2html: unable to open or read file ../mann/CollectionView::ReadFrom.n

man2html: unable to open or read file ../mann/CollectionView::SetCollection.n

man2html: unable to open or read file ../mann/CollectionView::SetDefaultItem.n

man2html: unable to open or read file ../mann/CollectionView::SetGap.n

man2html: unable to open or read file ../mann/CollectionView::SetMenu.n

man2html: unable to open or read file ../mann/CollectionView::SetMinExtent.n

man2html: unable to open or read file ../mann/CollectionView::SetNoSelection.n

man2html: unable to open or read file ../mann/CollectionView::SetOrigin.n

man2html: unable to open or read file ../mann/CollectionView::SetSelection.n

man2html: unable to open or read file ../mann/CollectionView::Update.n

man2html: unable to open or read file ../mann/CollectionView::~CollectionView.n

This document was created by man2html, using the manual pages.
Time: 00:40:30 GMT, March 30, 2022